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I!! 


PREFACE 


This  paper  describes  the  software  design  of  the  Desktop  Decision  Trainer  (DDT) 
developed  in  support  of  the  “Desktop  Training  for  Logistics  Command  and  Control 
(LC2)”  research  and  development  effort.  This  project  was  accomplished  under  contract 
number  F33615-91-C-0007,  with  System  Engineering  Associates  (SEA),  San  Diego,  CA. 
Management  of  this  project  was  provided  by  the  Human  Resources  Directorate, 
Technical  Training  Research  Division,  Instructional  Systems  Branch  (AL/HRTD). 


IV 


SUMMARY 


Logistics  Command  and  Control  (LC2)  units  must  ensure  that  core  and  augmentee 
personnel  are  fully  trained  in  the  combat  critical  skills  of  decision  making.  At  present, 
existing  training  capabilities  are  inadequate.  They  consist  of  primarily  expensive  and 
manpower-intensive  exercises  which  afford  only  sporadic  training  opportunities.  These 
opportunities  are  considered  insufficient  to  achieve  and  maintain  the  skill  levels  required 
for  successful  combat  operations.  The  need  for  more  accessible,  affordable  and  less 
manpower-intensive  training  continues  to  exist. 

In  1991,  the  Armstrong  Laboratory  Human  Resources  Directorate  (AL/HR)  began 
research  and  development  efforts  to  improve  decision-making  training  for  Logistics 
centers  throughout  the  Air  Force.  A  contract  was  let  with  Systems  Engineering 
Associates  (SEA)  to  produce  a  computer-based  decision  trainer  to  provide  individual 
instruction  and  enable  students  to  practice  solving  realistic  logistics  problems  within  a 
simulation  environment.  The  project  began  in  February  1992  and  concluded  in  February 
1997. 


This  paper  describes  the  software  design  of  the  decision  trainer,  and  in  particular, 
how  the  system  implements  the  instructional  strategy  developed  to  teach  decision-making 


1.  DDT  ARCHITECTURE  REVIEW 


User  feedback  from  the  first  version  of  the  DDT  indicated  that  although  interactive  story 
model  was  very  useful,  the  user  interface  needed  improvement  and  the  logistical  model 
was  more  complex  than  was  needed  to  teach  the  skills  in  question.  In  order  to  quickly 
respond  to  riser  feedback  about  the  interface  and  to  lower  development  cost,  the 
architecture  of  the  DDT  has  been  changed  to  include  Visual  Basic  for  creating  the  user 
interface,  while  still  preserving  the  investment  in  the  C++  code  used  to  implement  the 
interactive  story.  This  document  describes  the  methodology  used  to  replace  the  C++  user 
interface  code  in  the  original  DDT  with  Visual  Basic.  The  interface  code  and  the  logistic 
simulation  code  were  stripped  from  the  original  DDT  and  the  remaining  interactive  story 
code  is  compiled  as  a  DLL  that  to  interface  with  Visual  Basic.  This  DLL  which  exports 
both  custom  controls  and  DLL  functions  to  Visual  Basic.  The  following  figure  illustrates 
the  coupling  between  the  DDT  simulation  and  Visual  Basic. 


Visual  Basic  Front  End 

Simulation  DLL 

Visual  Basic  Custom  Controls 

DLL  Functional  interface 

Figure  1.  Coupling  between  DDT  Simulation  and  Visual  Basic 


The  original  DDT  simulation  is  divided  into  three  engines.  The  first  engine  models  a 
logistical  network,  the  second  models  an  interactive  story,  and  the  third  models  a  decision 
option  structure.  The  new  DDT  simulation  DLL  contains  only  the  interactive  story 
model  and  the  agency  object  from  the  logistical  network  model.  The  logistical  network 
model  and  the  decision  option  structure  have  been  simplified  and  implemented  in  Visual 
Basic  using  MS  Access  databases.  MS  Access  databases  have  also  been  used  to 
implement  portions  of  the  interactive  story.  The  following  section  describes  the  DDT 
simulation  DLL’s  interactive  story  engine  and  its  interfaces  with  Visual  Basic. 

Subsequent  sections  discuss  the  databases  used  to  implement  the  logistics  network  and 
the  decision  options  structure. 
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2.  Interactive  Story  Engine 

The  interactive  story  engine  is  managed  by  the  case  objects.  Each  case  object  consists  of 
a  list  of  messages,  topics,  and  information  deposits.  Below  is  a  list  of  the  objects  used  in 
the  story  engine  and  a  diagram  of  each  object's  class  structure. 


2.1  Case  Object: 


2.2 


Message: 


2.3  Information  Deposit: 


In  the  original  DDT,  these  objects  contain  C++  user  interface  code  within  their  structure. 
The  two  main  user  interface  hooks  for  retrieving  information  from  the  story  engine  are 
the  message  desk  and  agency  query  screens.  Below  is  a  description  of  the  original 
message  desk  and  agency  query  screens,  along  with  their  Visual  Basic  versions. 

2.4  Original  Message  Desk  GUI 

The  original  message  desk  screen  is  controlled  by  the  DeskManager  object.  This 
object  manages  five  fists  of  messages. 

•  TodoDesk  -  List  of  messages  on  the  todo  fist  window. 

•  FileDesk  -  List  of  messages  on  the  file  cabinet  window. 

•  TrashDesk  -  List  of  messages  placed  in  the  trash  can. 

•  ForwardDesk  -  List  of  forwarded  messages. 

•  MessageDesk  -  List  of  message  on  the  message  desk  window. 
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The  DeskManager  object  handles  the  display  and  movement  of  messages  in  the 
GUI  using  the  following  four  methods. 

•  AddToList  -  Adds  a  message  to  one  of  the  five  lists. 

•  RemoveFromList  -  Deletes  a  message  from  one  of  the  five  fists. 

•  HideMessageList  -  Hides  the  message  for  the  give  fist. 

•  ShowMessageList  -  Shows  the  message  for  the  given  fists. 

2.5  Visual  Basic  Message  Desk  GUI 

To  implement  the  message  desk  user  interface  in  Visual  Basic,  the  engine  exports 
the  following  group  of  custom  controls,  event  methods,  and  DLL  functions: 

2.5.1  MessageList  Custom  Control 

The  MessageList  custom  control  exports  the  four  fists  used  by  the  DeskManager 
object  to  VB.  This  Control  acts  as  a  data  server  from  the  simulation  DLL  to  VB. 
The  control  is  not  visible  to  the  user. 

2.5.2.  Properties: 

LpMessageObj 
MessageCount 
Messagelndex 
LpFolderObj  - 
FolderCount  — 

Folderlndex  — 

LpForwardObj 
ForwardCount 
Forwardlndex 
LpTrashObj  — 

TrashCount  — 

Trashlndex  — 


i -  Long  pointer  to  a  message  object. 

-  Count  of  objects  on  the  MessageDeskList. 

-  Index  of  current  fist  object. 

-  Long  pointer  to  a  message  object. 

—  Count  of  objects  on  the  FileDeskList. 

—  Index  of  current  fist  object. 

-  Long  pointer  to  a  message  object. 

-  Count  of  objects  on  the  ForwardDeskList. 

-  Index  of  current  fist  object. 

—  Long  pointer  to  a  message  object. 

—  Count  ofobjects  on  the  TrashDeskList. 

—  Index  of  current  fist  object. 
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2.5.3.  Events: 

MessageAdded(List  ID,  LpMessageObj) 

MessageDeleted(List  ID,  LpMessageObj) 

These  events  are  triggered  by  changes  to  the 
message  lists  listed  above.  The  MessageAdded 
event  is  triggered  when  mail  arrives.  VB  code  for 
these  events  handles  displaying  messages  on  the 
desk  and  folder  windows. 

2.5.4.  DLL  Functions: 

MoveMessage(SourceListID,  DestinationListID,  LpMessage) 

Tells  the  engine  to  move  a  message  from  one  list  to  another.  The 
engine  then  fires  the  AddMessage  and  DeleteMessage  events. 

2.6  Message  Custom  Control 

The  Message  custom  control  displays  a  picture  of  a  message.  The  control  sits  on 
the  message  desk  window.  Visual  Basic  (VB)  code  instantiates  message  controls 
depending  on  the  contents  of  the  message  lists.  When  one  of  these  controls  is 
clicked  on,  it  calls  the  Show  method  of  its  InfoPac  causing  the  available  topics  list 
to  be  reevaluated,  then  it  passs  the  database  key  of  its  InfoPac  to  VB  in  the  click 
event  so  that  VB  can  display  the  contents  of  the  InfoPac. 

2.6.1.  Properties: 

LpMessageObj 

Subject - 

Sender - 

LpInfoPac - 

Picture  - 

2.6.2.  Events: 

Click(FileName,  FileType) 

2.7.  Original  Agency  Query  User  Interface 

The  original  agency  query  user  interface  consists  of  an  agency  listbox  and  a  topic 
listbox.  The  user  selects  an  agency  from  the  agency  listbox  then  selects  a  topic 
from  the  topic  listbox.  The  listboxes  contain  pointers  to  agency  and  topic  C++ 
objects.  Once  the  user  has  selected  an  agency  and  topic,  DoInfoDeposit  is  called 
to  display  the  information  packet  and  mark  the  topic  as  discovered. 


-  Long  pointer  to  a  message  object. 

String  subject  of  message. 

String  Name  of  sending  agency. 

Long  pointer  to  infopac  object. 

Bitmap  or  metafile  depiction  of  the  closed  message. 
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2.8.  Visual  Basic  Agency  Query  User  Interface 

To  implement  the  agency  query  user  interface  in  Visual  Basic,  the  simulation 
exports  the  following  group  of  custom  controls. 

2.9.  AgencyList  Custom  Control  (Non-Location) 

The  AgencyList  custom  control  exports  the  list  of  non-location  agencies,  and 
optionally  displays  them  in  a  list  box  for  user  selection.  The  Lp Agency Obj, 
Agencylndex,  AgencyName,  CommMug  properties  are  all  set  when  the  user 
clicks  to  reflect  the  currently  selected  agency  in  the  list  box.  The  currently 
selected  agency  in  the  list  box  changes  whenever  the  LpAgencyObj  or 
Agencylndex  properties  are  set  by  VB  code.  A  click  event  is  generated  whenever 
the  user  selects  an  agency  in  the  listbox,  allowing  the  control  to  be  used  both  as  a 
VB  interface  to  the  agencies  list  and  as  an  agency  selection  control. 

2.9.1.  Properties: 

LpAgencyObj 

AgencyCount 
Agencylndex  - 
AgencyName 
CommMug  — 

Visible - 

2.9.2.  Events: 

ClickO 

2.10.  TopicList  Custom  Control 

The  TopicList  custom  control  exports  the  list  of  currently  active  topics,  and 
optionally  displays  them  in  a  list  box  for  user  selection.  The  LpTopicObj, 
Topiclndex,  Topiclndex  properties  are  all  set  when  the  user  clicks  to  reflect  the 
currently  selected  topic  in  the  list  box.  The  currently  selected  topic  in  the  list  box 
changes  whenever  the  LpTopicObj  or  Topiclndex  properties  are  set  by  VB  code. 

A  click  event  is  generated  whenever  the  user  selects  a  topic  in  the  listbox, 
allowing  the  control  to  be  used  both  as  a  VB  interface  to  the  active  topics  list  and 
as  a  topic  selection  control.  The  addition  of  the  LpAgencyObj  property  allows  the 
control  to  operate  as  a  complete  agency  query  control.  When  the  LpAgencyObj 
property  points  to  a  valid  agency,  and  the  user  choses  a  topic  from  the  listbox,  the 
control  finds  the  appropriate  InfoPac  and  returns  the  file  name  or  database  key  and 
file  type  in  the  click  event  so  that  VB  code  can  display  the  result  of  the  agency 
query.  The  control  also  handles  the  topic  list  reevaluation. 


Long  pointer  to  a  agency  object,  (read- write  at 
runtime) 

Count  of  agencies  on  the  list,  (read-only  at  runtime) 
Index  of  current  list  object,  (read- write  at  runtime) 

String  name  of  the  current  agency,  (read-only  at  runtime) 
Picture  property,  (read-only  at  runtime) 

Determines  if  the  control  displays  a  listbox. 
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2.10.1.  Properties: 


LpTopicObj, 

Long  pointer  to  a  topic  object. 

TopicCount, 

Count  of  topics  on  the  list. 

Topiclndex, 

Index  of  current  list  object. 

Topiclndex, 

String  name  of  topic. 

Lp  Agency Obj, 

Long  pointer  to  an  agency  object,  (read- write  at 
runtime) 

QueryOnClick, 

Boolean  indicating  whether  the  control  should 
actually  perform  the  query  when  the  user  clicks. 

QueryTrigger, 

Boolean  that  when  set  to  TRUE  performs  the  query 
for  the  currently  selected  topic  and  the  current  value 
of  LpAgencyObj,  and  programmatically  generates 
the  appropriate  click  event. 

2.10.2.  Events: 

Click(FileName,  FileType) 

Place  VB  code  in  the  Click  event  to  “display”  the  contents  of  the 
file  or  database  record. 


3.  Visual  Basic  Decision  Options  Structure 

The  Visual  Basic  decision  options  structure  is  implemented  in  a  module  called 
options.bas.  This  module  contains  the  data  structure  definitions  and  the  code  for 
manipulating  those  data  structures.  Because  the  decisions  options  structure  and  the 
logistics  network  are  so  closely  related,  this  module  also  contains  the  data  structures  and 
code  for  manipulating  the  logistics  network.  The  logistics  network  configuration  for  each 
case  is  stored  in  an  MS  Access  database.  The  decision  options  structure  consists  of  the 
following  Visual  Basic  data  structures: 

Type  Leg 

EmbarkPortldx  As  Integer 
ArrivalPortldx  As  Integer 
FMIdx  As  FreightMission 

End  Type 

Type  Shipment 

Sourceldx  As  Integer 
Quantity  As  Integer 
Destldx  As  Integer 
Legs(MAXLEGS)  As  Leg 
TotCost  As  Single 
Cost  As  String 
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Risk  As  Single 
FirstArrival  As  String 
arrivalamount  As  String 
End  Type 

Type  DDTOption 

Shipments(3)  As  Shipment 
Amounts(13)  As  Single 
TempFMTableName  As  String 
Evaluated  As  Integer 
accessed  As  Integer 
End  Type 

The  student  can  respond  to  a  logistics  problem  by  specifying  several  (up  to  four)  options 
and  then  choosing  the  best  option  as  the  solution  to  the  problem.  An  option  consists  of 
several  shipments  (up  to  three)  and  each  shipment  consists  of  several  legs.  On  each  leg, 
the  shipment  travels  via  a  particular  Freight  Mission.  The  decision  options  structure  is 
built  using  the  above  types  as  the  user  interacts  with  the  system.  The  commodities  and 
freight  missions  that  the  user  has  to  choose  from  are  specified  for  each  case  in  the  case 
database.  The  case  database  consists  of  the  following  tables: 

CaseParameters 

Commodities 

FMMaster 

InfoPackets 

The  CaseParameters  table  contains  basic  information  about  the  case  including  the  name 
of  the  text  file  that  defines  the  structure  of  the  interactive  story.  This  table  also  contains 
information  used  to  evaluate  the  students  solution  to  the  case.  The  commodities  table 
contains  information  about  the  amount  of  the  commodity  in  question  available  at  each 
location.  The  FMMaster  table  contains  information  about  all  of  the  scheduled  freight 
missions  available  in  the  case.  The  InfoPackets  table  contains  all  of  the  text  related  to  the 
interactive  story.  In  the  future  these  fields  might  also  contain  multimedia  data  such  as 
sound  or  video. 


4.  Reference  Desk 

The  Reference  desk  can  be  accessed  by  the  student  during  the  simulation  to 
provide  basic  information  about  commodities,  locations,  etc.  In  the  original  DDT 
this  feature  was  not  yet  implemented.  The  current  interface  has  two  levels  of 
menus  with  the  actual  information  being  presented  in  fixed  panes  on  the  screen. 
This  is  accomplished  using  data  aware  widgets  in  the  fixed  panes  to  display 
pictures  contained  in  an  MS  Access  database,  and  using  the  menu  widgets  to 
position  the  database. 
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